hashids

What is hashids?

The hashids npm package is a small JavaScript library that generates short, unique, non-sequential ids from numbers. It is useful for creating URL-friendly ids, obfuscating database ids, and more.

What are hashids's main functionalities?

Encoding Numbers

This feature allows you to encode a single number into a unique, short string. This is useful for creating URL-friendly ids.

const Hashids = require('hashids/cjs');
const hashids = new Hashids();
const id = hashids.encode(12345);
console.log(id); // e.g., 'NkK9'

Decoding Numbers

This feature allows you to decode a previously encoded string back into the original number. This is useful for retrieving the original id from a URL-friendly id.

const Hashids = require('hashids/cjs');
const hashids = new Hashids();
const numbers = hashids.decode('NkK9');
console.log(numbers); // [12345]

Encoding Multiple Numbers

This feature allows you to encode multiple numbers into a single unique string. This can be useful for combining multiple ids into one.

const Hashids = require('hashids/cjs');
const hashids = new Hashids();
const id = hashids.encode(1, 2, 3);
console.log(id); // e.g., 'laHquq'

Decoding Multiple Numbers

This feature allows you to decode a previously encoded string back into the original set of numbers. This is useful for retrieving multiple ids from a single URL-friendly id.

const Hashids = require('hashids/cjs');
const hashids = new Hashids();
const numbers = hashids.decode('laHquq');
console.log(numbers); // [1, 2, 3]

Custom Alphabet

This feature allows you to specify a custom alphabet for encoding. This can be useful for ensuring that the generated ids meet specific requirements or constraints.

const Hashids = require('hashids/cjs');
const hashids = new Hashids('', 0, 'abcdefghijklmnopqrstuvwxyz');
const id = hashids.encode(12345);
console.log(id); // e.g., 'dplb'

Other packages similar to hashids

shortid

The shortid package generates short, unique, non-sequential ids. It is similar to hashids in that it creates URL-friendly ids, but it does not provide the ability to encode and decode numbers.

nanoid

The nanoid package is a tiny, secure, URL-friendly, unique string ID generator. It is similar to hashids in that it creates short, unique ids, but it focuses on security and performance rather than encoding and decoding numbers.

uuid

The uuid package generates RFC-compliant UUIDs (Universally Unique Identifiers). It is different from hashids in that it generates longer, globally unique ids, and does not provide the ability to encode and decode numbers.

README

Hashids is small JavaScript library to generate YouTube-like ids from numbers. Use it when you don't want to expose your database ids to the user: http://hashids.org/javascript

Getting started

Install Hashids via:

• node.js: npm install --save hashids
• bower: bower install hashids
• jam: jam install hashids

(or just use the code at dist/hashids.js)

Use in the browser (wherever ES5 is supported; 5KB):

<script type="text/javascript" src="hashids.min.js"></script>
<script type="text/javascript">

    var hashids = new Hashids();
    console.log(hashids.encode(1));

</script>

Use in Node.js:

var Hashids = require('hashids');
var hashids = new Hashids();

console.log(hashids.encode(1));

Quick example

var hashids = new Hashids();

var id = hashids.encode(1, 2, 3); // o2fXhV
var numbers = hashids.decode(id); // [1, 2, 3]

More options

A few more ways to pass to encode():

var hashids = new Hashids();

console.log(hashids.encode(1, 2, 3)); // o2fXhV
console.log(hashids.encode([1, 2, 3])); // o2fXhV
console.log(hashids.encode('1', '2', '3')); // o2fXhV
console.log(hashids.encode(['1', '2', '3'])); // o2fXhV

Make your ids unique:

Pass a project name to make your ids unique:

var hashids = new Hashids('My Project');
console.log(hashids.encode(1, 2, 3)); // Z4UrtW

var hashids = new Hashids('My Other Project');
console.log(hashids.encode(1, 2, 3)); // gPUasb

Use padding to make your ids longer:

Note that ids are only padded to fit at least a certain length. It doesn't mean that your ids will be exactly that length.

var hashids = new Hashids(); // no padding
console.log(hashids.encode(1)); // jR

var hashids = new Hashids('', 10); // pad to length 10
console.log(hashids.encode(1)); // VolejRejNm

Pass a custom alphabet:

var hashids = new Hashids('', 0, 'abcdefghijklmnopqrstuvwxyz'); // all lowercase
console.log(hashids.encode(1, 2, 3)); // mdfphx

Default alphabet is abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890.

Encode hex instead of numbers:

Useful if you want to encode Mongo's ObjectIds. Note that there is no limit on how large of a hex number you can pass (it does not have to be Mongo's ObjectId).

var hashids = new Hashids();

var id = hashids.encodeHex('507f1f77bcf86cd799439011'); // y42LW46J9luq3Xq9XMly
var hex = hashids.decodeHex(id); // 507f1f77bcf86cd799439011

Pitfalls

1. When decoding, output is always an array of numbers (even if you encode only one number):

   var hashids = new Hashids();
   
   var id = hashids.encode(1);
   console.log(hashids.decode(id)); // [1]
   

2. Encoding negative numbers is not supported.

3. If you pass bogus input to encode(), an empty string will be returned:

   var hashids = new Hashids();
   
   var id = hashids.encode('123a');
   console.log(id === ''); // true
   

4. Do not use this library as a security tool and do not encode sensitive data. This is not an encryption library.

Randomness

The primary purpose of Hashids is to obfuscate ids. It's not meant or tested to be used as a security or compression tool. Having said that, this algorithm does try to make these ids random and unpredictable:

No repeating patterns showing there are 3 identical numbers in the id:

var hashids = new Hashids();
console.log(hashids.encode(5, 5, 5)); // A6t1tQ

Same with incremented numbers:

var hashids = new Hashids();

console.log(hashids.encode(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)); // wpfLh9iwsqt0uyCEFjHM

console.log(hashids.encode(1)); // jR
console.log(hashids.encode(2)); // k5
console.log(hashids.encode(3)); // l5
console.log(hashids.encode(4)); // mO
console.log(hashids.encode(5)); // nR

Curses! #$%@

This code was written with the intent of placing created ids in visible places, like the URL. Therefore, the algorithm tries to avoid generating most common English curse words by generating ids that never have the following letters next to each other:

c, f, h, i, s, t, u

License

MIT License. See the LICENSE file. You can use Hashids in open source projects and commercial products. Don't break the Internet. Kthxbye.